[![](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/H-IAAC/CST-SUMO-controller) # CST-SUMO Controller This repository contains a CST-Python based controller that orchestrates a SUMO mobility simulation, triggers a clustering step, and exchanges state through Redis. This project was developed as part of the Cognitive Architectures research line from the Hub for Artificial Intelligence and Cognitive Architectures (H.IAAC) of the State University of Campinas (UNICAMP). See more projects from the group [here](https://h-iaac.github.io/HIAAC-Index). [![](https://img.shields.io/badge/-H.IAAC-eb901a?style=for-the-badge&labelColor=black)](https://hiaac.unicamp.br/) [![](https://img.shields.io/badge/-Arq.Cog-black?style=for-the-badge&labelColor=white&logo=data:image/svg%2bxml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4gPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI1Ni4wMDQiIGhlaWdodD0iNTYiIHZpZXdCb3g9IjAgMCA1Ni4wMDQgNTYiPjxwYXRoIGlkPSJhcnFjb2ctMiIgZD0iTTk1NS43NzQsMjc0LjJhNi41Nyw2LjU3LDAsMCwxLTYuNTItNmwtLjA5MS0xLjE0NS04LjEtMi41LS42ODksMS4xMjNhNi41NCw2LjU0LDAsMCwxLTExLjEzNi4wMjEsNi41Niw2LjU2LDAsMCwxLDEuMzY4LTguNDQxbC44LS42NjUtMi4xNS05LjQ5MS0xLjIxNy0uMTJhNi42NTUsNi42NTUsMCwwLDEtMi41OS0uODIyLDYuNTI4LDYuNTI4LDAsMCwxLTIuNDQzLTguOSw2LjU1Niw2LjU1NiwwLDAsMSw1LjctMy4zLDYuNDU2LDYuNDU2LDAsMCwxLDIuNDU4LjQ4M2wxLC40MSw2Ljg2Ny02LjM2Ni0uNDg4LTEuMTA3YTYuNTMsNi41MywwLDAsMSw1Ljk3OC05LjE3Niw2LjU3NSw2LjU3NSwwLDAsMSw2LjUxOCw2LjAxNmwuMDkyLDEuMTQ1LDguMDg3LDIuNS42ODktMS4xMjJhNi41MzUsNi41MzUsMCwxLDEsOS4yODksOC43ODZsLS45NDcuNjUyLDIuMDk1LDkuMjE4LDEuMzQzLjAxM2E2LjUwNyw2LjUwNywwLDAsMSw1LjYwOSw5LjcyMSw2LjU2MSw2LjU2MSwwLDAsMS01LjcsMy4zMWgwYTYuNCw2LjQsMCwwLDEtMi45ODctLjczMmwtMS4wNjEtLjU1LTYuNjgsNi4xOTIuNjM0LDEuMTU5YTYuNTM1LDYuNTM1LDAsMCwxLTUuNzI1LDkuNjkxWm0wLTExLjQ2MWE0Ljk1LDQuOTUsMCwxLDAsNC45NTIsNC45NUE0Ljk1Nyw0Ljk1NywwLDAsMCw5NTUuNzc0LDI2Mi43MzlaTTkzNC44LDI1Ny4zMjVhNC45NTIsNC45NTIsMCwxLDAsNC4yMjEsMi4zNDVBNC45Myw0LjkzLDAsMCwwLDkzNC44LDI1Ny4zMjVabS0uMDIyLTEuNThhNi41MTQsNi41MTQsMCwwLDEsNi41NDksNi4xTDk0MS40LDI2M2w4LjA2MSwyLjUuNjg0LTEuMTQ1YTYuNTkxLDYuNTkxLDAsMCwxLDUuNjI0LTMuMjA2LDYuNDQ4LDYuNDQ4LDAsMCwxLDIuODQ0LjY1bDEuMDQ5LjUxOSw2LjczNC02LjI1MS0uNTkzLTEuMTQ1YTYuNTI1LDYuNTI1LDAsMCwxLC4xMTUtNi4yMjksNi42MTgsNi42MTgsMCwwLDEsMS45NjYtMi4xMzRsLjk0NC0uNjUyLTIuMDkzLTkuMjIyLTEuMzM2LS4wMThhNi41MjEsNi41MjEsMCwwLDEtNi40MjktNi4xbC0uMDc3LTEuMTY1LTguMDc0LTIuNS0uNjg0LDEuMTQ4YTYuNTM0LDYuNTM0LDAsMCwxLTguOTY2LDIuMjY0bC0xLjA5MS0uNjUyLTYuNjE3LDYuMTMxLjc1MSwxLjE5MmE2LjUxOCw2LjUxOCwwLDAsMS0yLjMsOS4xNjRsLTEuMS42MTksMi4wNiw5LjA4NywxLjQ1MS0uMUM5MzQuNDc1LDI1NS43NSw5MzQuNjI2LDI1NS43NDQsOTM0Ljc3OSwyNTUuNzQ0Wm0zNi44NDQtOC43NjJhNC45NzcsNC45NzcsMCwwLDAtNC4zMTYsMi41LDQuODg5LDQuODg5LDAsMCwwLS40NjQsMy43NjIsNC45NDgsNC45NDgsMCwxLDAsNC43NzktNi4yNjZaTTkyOC43LDIzNS41MzNhNC45NzksNC45NzksMCwwLDAtNC4zMTcsMi41LDQuOTQ4LDQuOTQ4LDAsMCwwLDQuMjkxLDcuMzkxLDQuOTc1LDQuOTc1LDAsMCwwLDQuMzE2LTIuNSw0Ljg4Miw0Ljg4MiwwLDAsMCwuNDY0LTMuNzYxLDQuOTQsNC45NCwwLDAsMC00Ljc1NC0zLjYzWm0zNi43NzYtMTAuMzQ2YTQuOTUsNC45NSwwLDEsMCw0LjIyMiwyLjM0NUE0LjkyMyw0LjkyMywwLDAsMCw5NjUuNDc5LDIyNS4xODdabS0yMC45NTItNS40MTVhNC45NTEsNC45NTEsMCwxLDAsNC45NTEsNC45NTFBNC45NTcsNC45NTcsMCwwLDAsOTQ0LjUyNywyMTkuNzcyWiIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTkyMi4xNDMgLTIxOC4yKSIgZmlsbD0iIzgzMDNmZiI+PC9wYXRoPjwvc3ZnPiA=)](https://h-iaac.github.io/HIAAC-Index) ## Overview The controller currently implements this execution flow: 1. Wait for a start signal in Redis. 2. Load a `SumoConfiguration` payload from Redis. 3. Build a CST-Python mind with four codelets. 4. Run the local SUMO backend on the bundled UNICAMP map. 5. Generate trajectory CSV files under `sumo_backend/data/`. 6. Call an external clustering API and extract its outputs. 7. Persist run metadata back to Redis. ## Current Status The current codebase behaves as follows: - The main execution path is implemented and starts in `main.py`. - Redis is mandatory for the default execution path. - SUMO assets for the UNICAMP map are committed under `sumo_backend/src/sumo_map/unicamp/`. - The clustering step depends on an HTTP service at `http://localhost:8000/cluster`. - `config/project.yaml` must define `cluster.output_ui_dir`, and the current default points to a machine-specific Unity project path. - The SUMO backend writes CSV outputs to disk, and the controller later runs clustering on `sumo_backend/data/traffic/ego.csv`. - The CST memories `GPSData` and `InCreationGPSBuffer` are present in the architecture, but the current SUMO backend writes trajectories directly to CSV instead of streaming timestamped samples into those memories. As a result, Redis persistence is currently more useful for run metadata than for a populated in-memory GPS buffer. ## Repository Structure - `main.py`: default entry point that waits for Redis input and runs the controller. - `sumo_controller/`: main Python package. - `sumo_controller/mind_factory.py`: builds the CST mind and wires memories and codelets. - `sumo_controller/adapters.py`: Redis storage adapter and auxiliary adapters. - `sumo_controller/interfaces.py`: integration contracts and the current SUMO API wrapper. - `sumo_controller/models.py`: input model used to normalize `SumoConfiguration`. - `sumo_controller/codelets/`: CST codelets for simulation, buffering, transfer, and clustering. - `sumo_backend/`: local SUMO execution backend, map assets, generated data, notebooks, and helper scripts. - `config/project.yaml`: project-level configuration, currently used for cluster output export. - `requirements.txt`: practical runtime dependencies for local execution. - `pyproject.toml`: package metadata and minimal install dependencies. ## Architecture The CST mind currently uses four codelets: - `SumoSimulatorCodelet`: loads the configuration, runs the SUMO backend, and updates `SimulationStatus`. - `BufferCreatorCodelet`: intended to copy timestamped GPS samples into a perceptual buffer. - `TFCClusterRunnerCodelet`: posts a CSV to the clustering API, extracts the resulting ZIP, and publishes output file paths. - `TransferCodelet`: persists the final buffer and run metadata through the storage adapter. The default `ClusterConfig` is built internally by `sumo_controller/mind_factory.py` and points the clustering step to `sumo_backend/data/traffic/ego.csv`. ## Dependencies / Requirements Minimum requirements: - Python 3.10 or newer - Redis server - SUMO installed locally - `curl` available on the system path - A clustering API listening on `http://localhost:8000/cluster` Python dependencies actually used at runtime include: - `cst-python` - `redis` - `pandas` - `numpy` - `scipy` - `sumolib` - `matplotlib` - `pyproj` Notes: - `pyproject.toml` declares only the package-level minimum dependencies. - `requirements.txt` is closer to the real local execution environment. - SUMO Python tooling may also require `SUMO_HOME` to be configured on your machine, depending on your installation. ## Installation / Usage Create a virtual environment and install the runtime dependencies: ```bash python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt python -m pip install -e . ``` Install SUMO on Ubuntu: ```bash sudo add-apt-repository ppa:sumo/stable sudo apt-get update sudo apt-get install sumo sumo-tools sumo-doc ``` Start Redis locally or point the controller to an existing Redis instance through `REDIS_URL`. Update `config/project.yaml` so that `cluster.output_ui_dir` points to a valid directory on your machine. Provide a `SumoConfiguration` payload in Redis. A complete example is available in `sumo_backend/configs/sumo_config.json`. Expected payload shape: ```json { "api": { "cut": 5, "epochs": 20 }, "sumo": { "behaviour": { "simulation": { "time_to_teleport": 100, "lateral_resolution": 0.8, "step_length": 0.01, "end_time": 1000, "end_time_random_trips": 1000 }, "vehicle": { "maxSpeed": 200, "accel": 2.6, "decel": 4.5, "speedFactor": 1.0, "minGap": 2.5, "emergencyDecel": 9.0, "vClass": "passenger" }, "locations": [ "home", "Instituto de Computação", "Instituto de Filosofia e Ciências Humanas", "Instituto de Geociências", "home" ] } } } ``` Default Redis keys: - Configuration key: `default_mind:memories:SumoConfiguration` - Start signal key: `default_mind:memories:SimulationStarted` - Start signal field: `I` To run the code: ```bash python3 main.py ``` When the controller is waiting, trigger the run by running the [Unity interface](https://github.com/H-IAAC/demo-user-simulator-unity). Optional environment variables: - `REDIS_URL`: Redis connection string. Default: `redis://localhost:6379/0` - `REDIS_KEY_PREFIX`: prefix for controller-managed output keys. Default: `sumo_controller` - `REDIS_TTL_SECONDS`: optional TTL for persisted Redis keys - `SUMO_CONFIGURATION_KEY`: overrides the Redis key used to load `SumoConfiguration` - `SUMO_START_SIGNAL_KEY`: overrides the Redis key used for the start signal - `SUMO_START_POLL_INTERVAL_SECONDS`: polling interval while waiting for the start signal - `SUMO_START_TIMEOUT_SECONDS`: optional timeout while waiting for the start signal ## Outputs After a successful run, the current implementation produces these artifacts: - SUMO CSV outputs under `sumo_backend/data/no_traffic/` and `sumo_backend/data/traffic/` - Cluster outputs extracted to the directory defined by `cluster.output_ui_dir` - Redis entries under the configured key prefix for episode metadata and buffer payloads, which may be empty in the current integration The clustering step expects enough rows in the input CSV. If the traffic CSV is too short, the codelet upsamples the data before sending it to the API. ## Known Limitations - The controller currently assumes a local clustering API at a fixed URL instead of a configurable endpoint. - The cluster input CSV path is currently hard-coded in the mind factory. - The default `config/project.yaml` value is machine-specific and will need to be changed on any other workstation. - The current architecture includes memory objects for GPS streaming, but the active SUMO backend persists trajectories directly to files instead of filling those memories step by step. ## Citation ```bibtex @software{my_citation, author = {Parede de Souza, Henrique and da Silva Florencio, Renan and Yuji Sakabe, Eduardo and Dornhofer Paro Costa, Paula}, title = {CST-SUMO Controller}, url = {https://github.com/H-IAAC/CST-SUMO-controller} } ``` ## Authors - (2026-) [Henrique Parede de Souza](https://github.com/Henrique-hpds): Computer Engineering student, FEEC-UNICAMP - (2026-) [Renan Florencio](https://github.com/RenanFlorencio): Computer Engineering student, FEEC-UNICAMP - (2026-) Eduardo Yuji Sakabe: PhD Candidate, FEEC-UNICAMP - (Advisor, 2026-) Paula Dornhofer Paro Costa: Professor, FEEC-UNICAMP ## Acknowledgements This study was financed, in part, by the São Paulo Research Foundation (FAPESP), Brazil. Process Number 2024/23473-6. Project supported by the brazilian Ministry of Science, Technology and Innovations, with resources from Law No. 8,248, of October 23, 1991